package cn.iocoder.yudao.module.system.service.teacherdashboard;

import cn.iocoder.yudao.module.system.controller.admin.teacherdashboard.vo.*;

import javax.validation.Valid;
import java.util.List;

/**
 * 教师看板 Service 接口
 *
 * @author 芋道源码
 */
public interface TeacherDashboardService {

    /**
     * 获取教师看板数据
     *
     * @param reqVO 查询请求
     * @return 教师看板数据
     */
    TeacherDashboardRespVO getTeacherDashboard(@Valid TeacherDashboardReqVO reqVO);

    /**
     * 获取班级概览信息
     *
     * @param reqVO 查询请求
     * @return 班级概览信息
     */
    TeacherDashboardRespVO.ClassBasicInfo getClassOverview(@Valid ClassOverviewReqVO reqVO);

    /**
     * 获取升学分析数据
     *
     * @param reqVO 查询请求
     * @return 升学分析数据
     */
    AdmissionAnalysisRespVO getAdmissionAnalysis(@Valid AdmissionAnalysisReqVO reqVO);

    /**
     * 获取班级成绩统计
     *
     * @param classId 班级ID
     * @param examId 考试ID
     * @return 成绩统计信息
     */
    TeacherDashboardRespVO.ScoreStatistics getClassScoreStatistics(Long classId, Long examId);

    /**
     * 获取班级升学预测统计
     *
     * @param classId 班级ID
     * @param examId 考试ID
     * @return 升学预测统计
     */
    TeacherDashboardRespVO.AdmissionPredictionStats getAdmissionPredictionStats(Long classId, Long examId);

    /**
     * 获取班级前N名学生
     *
     * @param classId 班级ID
     * @param examId 考试ID
     * @param topN 前N名
     * @return 前N名学生信息
     */
    List<TeacherDashboardRespVO.TopStudentInfo> getTopStudents(Long classId, Long examId, Integer topN);

    /**
     * 获取进步最大的学生
     *
     * @param classId 班级ID
     * @param currentExamId 当前考试ID
     * @param previousExamId 上次考试ID
     * @param limit 限制数量
     * @return 进步学生信息
     */
    List<TeacherDashboardRespVO.ProgressStudentInfo> getMostImprovedStudents(Long classId, Long currentExamId, Long previousExamId, Integer limit);

    /**
     * 获取需要关注的学生
     *
     * @param classId 班级ID
     * @param currentExamId 当前考试ID
     * @param previousExamId 上次考试ID
     * @return 需要关注的学生信息
     */
    List<TeacherDashboardRespVO.AttentionStudentInfo> getAttentionStudents(Long classId, Long currentExamId, Long previousExamId);

    /**
     * 获取临界学生分析
     *
     * @param classId 班级ID
     * @param examId 考试ID
     * @param range 临界分数范围
     * @return 临界学生分析
     */
    TeacherDashboardRespVO.CriticalStudentAnalysis getCriticalStudentAnalysis(Long classId, Long examId, Integer range);

    /**
     * 获取班级在年级中的排名
     *
     * @param classId 班级ID
     * @param examId 考试ID
     * @return 班级排名
     */
    Integer getClassRankInGrade(Long classId, Long examId);

    /**
     * 获取班级升学趋势分析
     *
     * @param classId 班级ID
     * @param limit 历史考试数量限制
     * @return 升学趋势分析
     */
    TeacherDashboardRespVO.AdmissionTrendAnalysis getAdmissionTrendAnalysis(Long classId, Integer limit);

    /**
     * 获取班级对比分析
     *
     * @param classId 班级ID
     * @param examId 考试ID
     * @return 对比分析
     */
    TeacherDashboardRespVO.ComparisonAnalysis getComparisonAnalysis(Long classId, Long examId);

    /**
     * 获取教学效果分析
     *
     * @param classId 班级ID
     * @param currentExamId 当前考试ID
     * @param previousExamId 上次考试ID
     * @return 教学效果分析
     */
    TeacherDashboardRespVO.TeachingEffectAnalysis getTeachingEffectAnalysis(Long classId, Long currentExamId, Long previousExamId);

    /**
     * 获取学生详细升学信息
     *
     * @param classId 班级ID
     * @param examId 考试ID
     * @return 学生升学详情列表
     */
    List<AdmissionAnalysisRespVO.StudentAdmissionDetail> getStudentAdmissionDetails(Long classId, Long examId);

    // 注意：generateAlerts方法已被移除，因为AlertInfo类在优化过程中被删除
    // 相关功能已整合到教学建议(TeachingSuggestion)中

}
